home *** CD-ROM | disk | FTP | other *** search
/ Shareware Grab Bag / Shareware Grab Bag.iso / 007 / basdlx12.arc / BASDLX.DOC next >
Text File  |  1987-02-03  |  21KB  |  661 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.              BASDLX (C) Copyright 1986-87 By Gustavo Verdun       Page 1
  8.  
  9.  
  10.                                      BASDLX.LIB
  11.  
  12.           Deluxe Library of functions written in assembly language for the
  13.                                    BASIC Compiler
  14.  
  15.           BASDLX, Basic Deluxe, is a library of powerful functions for com-
  16.           piled BASIC.  To use  BASDLX.LIB you will need,  either  the  IBM
  17.           Basic  compiler or the Microsoft Quickbasic compiler.  I  suggest
  18.           that you use PC-DOS/MS-DOS versions 2.0 or later to  insure  full
  19.           compatibility. These routines have been tested with the IBM Basic
  20.           compiler version 2.0 and have caused no problems.  However,  I am
  21.           not responsible for any damages caused by but,  not  limited  to,
  22.           the use,  misuse or inability to use BASDLX.   These deluxe func-
  23.           tions are intended to be used in compiled basic only. Do not con-
  24.           fuse compiled BASIC with  the  BASIC  interpreter,  BASIC.COM  or
  25.           BASICA.COM  that  comes with DOS.  The functions provided in this
  26.           library have been designed to run faster than it's  correspondent
  27.           basic code,  and often take up less space,  leaving you with more
  28.           room to write longer programs!
  29.  
  30.           This is the Second,  of many public releases of the Basic  Deluxe
  31.           library. You are free to use the functions provided in the BASDLX
  32.           library  in your programs. The copyright is only here to preserve
  33.           my work and to protect you from any unauthorized modifications of
  34.           BASDLX;  it  is NOT here to protect against the free distribution
  35.           of BASDLX.  You may copy and distribute BASDLX to  others as long
  36.           as no  fee or special consideration is charged and all of the re-
  37.           lated  files  to  BASDLX  are included together in the unmodified
  38.           form.  If you use BASDLX in your programs and find it a  valuable
  39.           tool  then I would appreciate it if you would send a contribution
  40.           ($25 suggested).  It  would be nice if you could acknowledge  use
  41.           of  BASDLX  functions  in your programs or documentation that use
  42.           them. Your contribution will go into a fund that will finance the
  43.           rental of a private BBS for contributors.  Your    privileges  on
  44.           this system will include: 50 minutes of access time per day,  and
  45.           a special on-line "BASDLX Request/Comment  Form"  where  you  may
  46.           request new functions, or comment on existing ones! You will also
  47.           be  able to download the latest version of BASDLX,  including the
  48.           source code.
  49.  
  50.           These routines have been incorporated into a library to make them
  51.           easily accessible by the DOS LINK.EXE program.   All you have  to
  52.           do  is  copy  BASDLX.LIB  to the directory or disk where you keep
  53.           your library files.   When you link your  programs that use func-
  54.           tions  from  BASDLX,   be sure to specify: BASDLX when the linker
  55.           prompts you for a Library [.LIB] file(s).  Please refer  to  your
  56.           DOS manual for more information on the LINK.EXE program.
  57.  
  58.  
  59.  
  60.                     --- BASDLX   Version 1.2   February 1987 ---
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.              BASDLX (C) Copyright 1986-87 By Gustavo Verdun       Page 2
  68.  
  69.                                     Special Notes
  70.  
  71.           The  functions  provided  in this library are available to you by
  72.           using the CALL command from compiled basic. All numeric variables
  73.           passed as arguments to the functions must  defined  as  integers.
  74.           This means that you can either globally set all numeric variables
  75.           to integers by issuing the DEFINT A-Z command at the beginning of
  76.           your program or,  you can declare a single variable as integer by
  77.           adding a "%" symbol at the end of its name. (i.e.  I%,  this will
  78.           declare the variable as being integer). I will always add the "%"
  79.           symbol  at  the  end of all my numeric variables in all of my ex-
  80.           amples, to remind you that they MUST be integers.
  81.  
  82.           The variable names used in my examples don't have to  be  exactly
  83.           the  same.  you  may  choose  other  names that would be more ap-
  84.           propriate. keep in mind that the variable types do have to be the
  85.           same in the argument list (i.e. strings must be strings, integers
  86.           must be integers).
  87.  
  88.           As I mentioned before I have tested these functions and they,  to
  89.           the best of my knowledge,  work bug free.  But,  if you happen to
  90.           find any bugs I'll be happy to fix them.  Be sure to  check  that
  91.           you  are  CALLing  the  functions properly.  That is that you are
  92.           sending the correct arguments to the function.  One of  the  most
  93.           common  error  that  occurs  is when the calling program sends to
  94.           the function an incorrect variable type.  Remember  that  numeric
  95.           variables must be declared integer.
  96.  
  97.           Since  this  is  the second of many releases of BASDLX I'm sure I
  98.           will get a lot of comments from you.  So please don't hesitate to
  99.           inform me of anything! If there is something you don't like about
  100.           BASDLX  then  please don't refrain from telling me,  I'll be more
  101.           than happy to fix it!
  102.  
  103.           Please refer any questions,  comments,  requests for new routines
  104.           or contributions to the following address:
  105.  
  106.                                  Gustavo  H. Verdun
  107.                                  6424 Hollins Drive
  108.                                  Bethesda, MD 20817
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.                     --- BASDLX   Version 1.2   February 1987 ---
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.              BASDLX (C) Copyright 1986-87 By Gustavo Verdun       Page 3
  128.  
  129.           Function Name: BSORTN
  130.           Arguments    : (Num_of_elements,Integer_array%(start))
  131.           type         : integer array service
  132.           Purpose      : Sorts an integer array in ascending order with
  133.                          negative numbers appearing at the end  in
  134.                          ascending order.
  135.  
  136.           Description:
  137.           Integer  variables  in  BASIC can contain numbers between -32,768
  138.           and 32,767.  This function does not distinguish between  negative
  139.           or positive numbers. It will sort the elements in ascending order
  140.           with  all  the negative numbers (if existing) appearing after the
  141.           positive numbers in ascending order.  Make sure that the array is
  142.           of type integer. Unpredictable results may occur if not!
  143.  
  144.           Example:
  145.           dim a%(300):print "Array Before sort:"
  146.           for i%=0 to 300:a%(i%)=int(rnd(1)*30000):print a%(i%),:next
  147.           enum%=301:call bsortn(enum%,a%(0))
  148.           rem enum%=301 because there are 301 elements in the array (0-300)
  149.           print "Array After sort:":for i%=0 to 300:print a%(i%),:next
  150.           rem the list should be sorted in ascending numerical order!
  151.  
  152.           Function Name: BSORTS
  153.           Arguments    : (Num_of_elements%,Array$(start_position))
  154.           Type         : String array service
  155.           Purpose      : Sorts a string array in ascending alphabetical
  156.                          order.
  157.  
  158.           Description:
  159.           The  first argument should contain the number of elements to sort
  160.           in the array. The second argument is the array itself. be sure to
  161.           specify   the   starting   position   in    the    array    [i.e.
  162.           BSORTS(elements%,a$(0))]
  163.           IMPORTANT:  All  of  the  elements  in  the array MUST have equal
  164.           lengths, if not, unpredictable results will occur to BASIC
  165.  
  166.           Example:
  167.           dim a$(10):a$(0)"First":a$(1)="Second":a$(2)="Third"
  168.           a$(3)="Fourth":a$(4)="Fifth":a$(5)="Sixth":a$(6)="Seventh"
  169.           a$(7)="Eighth":a$(8)="Ninth":a$(9)="Tenth"
  170.           for i%=0 to 9:b$=space$(10):call setl(a$(i%),b$):a$(i%)=b$:next
  171.           rem the above line will make all of the elements in the array
  172.           rem have equal lengths.
  173.           print "Array before sort:":for i%=0 to 9:print a$(i%):next
  174.           enum%=10:call bsorts(enum%,a$(0))
  175.           rem enum%=10 because there are 10 elements  in  the  array  (0-9)
  176.           print "Array After sort:":for i%=0 to 9:print a$(i%):next
  177.           rem the list should be sorted in ascending alphabetical order!
  178.  
  179.  
  180.                     --- BASDLX   Version 1.2   February 1987 ---
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.              BASDLX (C) Copyright 1986-87 By Gustavo Verdun       Page 4
  188.  
  189.           Function Name: GUN
  190.           Arguments    : (Num_of_shots%)
  191.           Type         : Speaker support
  192.           Purpose      : Simulates the sound of a gun or machine gun
  193.  
  194.           Description  :
  195.           This  function  generates  the  sound  by sending spurts of white
  196.           noise to the speaker.  This will create the sound of a quick  ex-
  197.           plosion.  the  only  parameter  needed  is the number of shots to
  198.           fire.
  199.  
  200.           Example:
  201.           input "Number of shots to fire :",shots%:if shots%=0 then end
  202.           call gun(shots%)
  203.  
  204.  
  205.  
  206.  
  207.  
  208.  
  209.  
  210.  
  211.  
  212.  
  213.  
  214.  
  215.  
  216.  
  217.  
  218.  
  219.  
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.                     --- BASDLX   Version 1.2   February 1987 ---
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.              BASDLX (C) Copyright 1986-87 By Gustavo Verdun       Page 5
  248.  
  249.           Function Name: READP
  250.           Arguments    : (Port_num%)
  251.           Type         : Printer support
  252.           Purpose      : Reads the printer status of the specified port
  253.                          number (1-3) and returns with the status byte
  254.                          for that port in the port_num% variable.
  255.  
  256.           Description:
  257.           The status byte of contains the following information:
  258.  
  259.           bit:     7    6    5    4    3    2-1  0
  260.                    |    |    |    |    |    |    |_Time out
  261.                    |    |    |    |    |    |_Unused
  262.                    |    |    |    |    |_1 = I/O Error
  263.                    |    |    |    |_1 = Selected
  264.                    |    |    |_1 = Out of Paper
  265.                    |    |_1 = Acknowledge
  266.                    |_1 = Not Busy
  267.  
  268.           IMPORTANT: This routine does not check for a valid  port  number.
  269.           Be sure that the port number is in the range of 1-3
  270.  
  271.           Example:
  272.           port%=1:call readp(port%):print port%
  273.           if port% and 32=32 then print "Printer is out of paper"
  274.           if port% and 128=0 then print "Printer is Off-line"
  275.  
  276.           Function Name: RESETP
  277.           Arguments    : (Port_num%)
  278.           Type         : Printer support
  279.           Purpose      : Resets the specified printer port number (1-3)
  280.                          and returns with its status byte (see the READP
  281.                          function description for information on the
  282.                          printer status byte)
  283.  
  284.           Description:
  285.           This  function  sends a  reset status through the parallel inter-
  286.           face of the specified port number.  This routine does  check  the
  287.           parameters  to  be sure that they are in the range of 1 to 3.  If
  288.           the port_num% argument is equal to -1  upon return then the  port
  289.           number is not valid.
  290.  
  291.           Example:
  292.           port%=1:call resetp(port%):print port%
  293.           if port%=-1 then print"Port number must be in the range of 1-3"
  294.           if port% and 32=32 then print "Printer is out of paper"
  295.           if port% and 128=0 then print "Printer is Off-line"
  296.  
  297.  
  298.  
  299.  
  300.                     --- BASDLX   Version 1.2   February 1987 ---
  301.  
  302.  
  303.  
  304.  
  305.  
  306.  
  307.              BASDLX (C) Copyright 1986-87 By Gustavo Verdun       Page 6
  308.  
  309.           Function Name: SETL
  310.           Arguments    : (Source_string$,Destination_string$)
  311.           Type         : String manipulation
  312.           Purpose      : This function will place the source string inside
  313.                          of the destination left-justified. If the source
  314.                          string is longer than the destination string then
  315.                          the right portion of the string will be truncated.
  316.  
  317.           Description:
  318.           This function automatically sets the destination string to spaces
  319.           (ASCII  32) even if the source string is of length zero.  Be sure
  320.           to save the destination string into the source string  after  the
  321.           function call.
  322.  
  323.           Example:
  324.           a$="Enter Name":b$=space(20):call setl(a$,b$):a$=b$
  325.           rem the last command "a$=b$" saves the destination string in the
  326.           rem source string since the function cant' change the length of
  327.           rem any string.
  328.           print ">";a$";"<":REM this will show you the new length of a$
  329.  
  330.           Function Name: SETR
  331.           Arguments    : (Source_string$,Destination_string$)
  332.           Type         : String manipulation
  333.           Purpose      : This function will place the source string inside
  334.                          the destination string right justified. If the
  335.                          destination string is shorter than the source
  336.                          string then the right portion of the string will
  337.                          be truncated.
  338.  
  339.           Description:
  340.           This  function  automatically  sets the destination string to all
  341.           spaces (ASCII 32) even if the source string is of length zero. Be
  342.           sure to save the destination string into the source string  after
  343.           the function call.
  344.  
  345.           Example:
  346.           a$="Enter Name":b$=space(20):call setr(a$,b$):a$=b$
  347.           rem the last command "a$=b$" saves the destination string in the
  348.           rem source string since the function cant' change the length of
  349.           rem any string.
  350.           print ">";a$;"<":REM this will show you the new length of a$
  351.  
  352.  
  353.  
  354.  
  355.  
  356.  
  357.  
  358.  
  359.  
  360.                     --- BASDLX   Version 1.2   February 1987 ---
  361.  
  362.  
  363.  
  364.  
  365.  
  366.  
  367.              BASDLX (C) Copyright 1986-87 By Gustavo Verdun       Page 7
  368.  
  369.           Function Name: SNDOFF
  370.           Arguments    : NONE
  371.           Type         : Speaker support
  372.           Purpose      : Turns speaker off. If this function is used then
  373.                          the BASIC SOUND or BEEP commands will not work.
  374.  
  375.           Description  :
  376.           This  function  can  be  useful for those programs that use sound
  377.           prompts to get attention when input is required.  With this func-
  378.           tion  you  can  easily add the feature to your programs that will
  379.           let the user decide if he wants to have the sound prompts  on  or
  380.           off.  If  he  wants the off then at the beginning of your program
  381.           just call this function. Any sound statements following this com-
  382.           mand will execute without producing a single sound.  Be sure  not
  383.           to forget to turn them on before the program finishes (SNDON).
  384.  
  385.  
  386.           Example :
  387.           sound 200,1:sound 300,1:sound 400,1:call sndoff
  388.           sound 200,1:sound 300,1:sound 400,1
  389.  
  390.  
  391.           Function Name: SNDON
  392.           Arguments    : NONE
  393.           Type         : Speaker support
  394.           Purpose      : Turns sound on so that the BASIC SOUND and BEEP
  395.                          commands work.
  396.  
  397.           Description:
  398.           This function can help solve the problem that occurs when you use
  399.           some  memory resident programs that use the speaker and when they
  400.           are done the turn it off so that any SOUND or BEEP commands won't
  401.           produce an audible signal.  It can also turn on the sound when it
  402.           was turned off by the function SNDOFF!
  403.  
  404.           Example:
  405.           sound 200,1:sound 300,1:sound 400,1:call sndoff
  406.           sound 200,1:sound 300,1:sound 400,1:call sndon
  407.           sound 200,1:sound 300,1:sound 400,1
  408.  
  409.  
  410.  
  411.  
  412.  
  413.  
  414.  
  415.  
  416.  
  417.  
  418.  
  419.  
  420.                     --- BASDLX   Version 1.2   February 1987 ---
  421.  
  422.  
  423.  
  424.  
  425.  
  426.  
  427.              BASDLX (C) Copyright 1986-87 By Gustavo Verdun       Page 8
  428.  
  429.           Function Name: XLC
  430.           Arguments    : (String$)
  431.           Type         : String manipulation
  432.           Purpose      : Converts the string to lower case.
  433.  
  434.           Description:
  435.           No further explanations are necessary, I hope!
  436.  
  437.           Example:
  438.           a="THIS WILL BE IN LOWER CASE!":call xlc(a$):print a$
  439.  
  440.           Function Name: XUC
  441.           Arguments    : (String$)
  442.           Type         : String manipulation
  443.           Purpose      : Converts the string to upper case.
  444.  
  445.           Description:
  446.           No further explanations are necessary, I hope!
  447.  
  448.           Example:
  449.           a="this will be in upper case!":call xuc(a$):print a$
  450.  
  451.  
  452.  
  453.  
  454.  
  455.  
  456.  
  457.  
  458.  
  459.  
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466.  
  467.  
  468.  
  469.  
  470.  
  471.  
  472.  
  473.  
  474.  
  475.  
  476.  
  477.  
  478.  
  479.  
  480.                     --- BASDLX   Version 1.2   February 1987 ---
  481.  
  482.  
  483.  
  484.  
  485.  
  486.  
  487.              BASDLX (C) Copyright 1986-87 By Gustavo Verdun       Page 9
  488.  
  489.                                 Summary of Functions
  490.  
  491.           Please use this as a quick summary to BASDLX functions. This sum-
  492.           mary  should  only be used once you understand the routines,  but
  493.           just need a quick refreshment.
  494.  
  495.           Function Name: BSORTN
  496.           Arguments    : (Num_of_elements,Integer_array%(start))
  497.           type         : integer variable service
  498.           Purpose      : Sorts an integer array in ascending order with
  499.                          negative numbers appearing at the end  in
  500.                          ascending order.
  501.  
  502.           Function Name: BSORTS
  503.           Arguments    : (Num_of_elements%,Array$(start_position))
  504.           Type         : String service
  505.           Purpose      : Sorts a string array in ascending alphabetical
  506.                          order.
  507.  
  508.           Function Name: GUN
  509.           Arguments    : (Num_of_shots%)
  510.           Type         : Speaker support
  511.           Purpose      : Simulates the sound of a gun or machine gun
  512.  
  513.           Function Name: READP
  514.           Arguments    : (Port_num%)
  515.           Type         : Printer support
  516.           Purpose      : Reads the printer status of the specified port
  517.                          number (1-3) and returns with the status byte
  518.                          for that port in the port_num% variable.
  519.  
  520.           Function Name: RESETP
  521.           Arguments    : (Port_num%)
  522.           Type         : Printer support
  523.           Purpose      : Resets the specified printer port number (1-3)
  524.                          and returns with its status byte (see the READP
  525.                          function description for information on the
  526.                          printer status byte)
  527.  
  528.           Function Name: SETL
  529.           Arguments    : (Source_string$,Destination_string$)
  530.           Type         : String manipulation
  531.           Purpose      : This function will place the source string inside
  532.                          of the destination left-justified. If the source
  533.                          string is longer than the destination string then
  534.                          the right portion of the string will be truncated.
  535.  
  536.  
  537.  
  538.  
  539.  
  540.                     --- BASDLX   Version 1.2   February 1987 ---
  541.  
  542.  
  543.  
  544.  
  545.  
  546.  
  547.             BASDLX (C) Copyright 1986-87 By Gustavo Verdun       Page 10
  548.  
  549.                             Summary of Functions (Cont.)
  550.  
  551.           Function Name: SETR
  552.           Arguments    : (Source_string$,Destination_string$)
  553.           Type         : String manipulation
  554.           Purpose      : This function will place the source string inside
  555.                          the destination string right justified. If the
  556.                          destination string is shorter than the source
  557.                          string then the right portion of the string will
  558.                          be truncated.
  559.  
  560.           Function Name: SNDOFF
  561.           Arguments    : NONE
  562.           Type         : Speaker support
  563.           Purpose      : Turns speaker off. If this function is used then
  564.                          the BASIC SOUND or BEEP commands will not work.
  565.  
  566.           Function Name: SNDON
  567.           Arguments    : NONE
  568.           Type         : Speaker support
  569.           Purpose      : Turns sound on so that the BASIC SOUND and BEEP
  570.                          commands work.
  571.  
  572.           Function Name: XLC
  573.           Arguments    : (String$)
  574.           Type         : String manipulation
  575.           Purpose      : Converts the string to lower case.
  576.  
  577.           Function Name: XUC
  578.           Arguments    : (String$)
  579.           Type         : String manipulation
  580.           Purpose      : Converts the string to upper case.
  581.  
  582.  
  583.  
  584.  
  585.  
  586.  
  587.  
  588.  
  589.  
  590.  
  591.  
  592.  
  593.  
  594.  
  595.  
  596.  
  597.  
  598.  
  599.  
  600.                     --- BASDLX   Version 1.2   February 1987 ---
  601.  
  602.  
  603.  
  604.  
  605.  
  606.  
  607.             BASDLX (C) Copyright 1986-87 By Gustavo Verdun       Page 11
  608.  
  609.  
  610.  
  611.  
  612.  
  613.  
  614.  
  615.  
  616.  
  617.  
  618.  
  619.  
  620.  
  621.  
  622.  
  623.  
  624.  
  625.  
  626.  
  627.  
  628.  
  629.  
  630.  
  631.  
  632.  
  633.  
  634.  
  635.  
  636.  
  637.  
  638.  
  639.  
  640.  
  641.  
  642.  
  643.  
  644.  
  645.  
  646.  
  647.  
  648.  
  649.  
  650.  
  651.  
  652.  
  653.  
  654.  
  655.  
  656.  
  657.  
  658.  
  659.  
  660.                     --- BASDLX   Version 1.2   February 1987 ---
  661.